%% This file is part of Enblend.
%% Licence details can be found in the file COPYING.


\subsection[Advanced Options\commonpart]{\label{sec:advanced-options}%
  \genidx[\rangebeginlocation]{advanced options}%
  \genidx{options!advanced}%
  Advanced Options\commonpart}

Advanced options control for example the channel depth, color model, and the cropping of the
output image.

\begin{codelist}
  \label{opt:blend-colorspace}%
  \optidx[\defininglocation]{--blend-colorspace}%
  \genidx{colorspace!blend}%
  \gensee{blend colorspace}{colorspace, blend}%
  \genidx{color appearance model}%
\item[--blend-colorspace=\metavar{COLORSPACE}]\itemend
  Force blending in selected \metavar{COLORSPACE}.  Given well matched images this option should
  not change the output image much.  However, if \App{} must blend vastly different colors (as
  for example anti-colors) the resulting image heavily depends on the \metavar{COLORSPACE}.

  Usually, \App{} chooses defaults depending on the input images:

  \begin{itemize}
    \genidx{profile!ICC@\acronym{ICC}}%
    \gensee{ICC@\acronym{ICC} profile}{profile, \acronym{ICC}}%
    \genidx{colorspace!CIELUV@\acronym{CIELUV}}%
  \item
    For grayscale or color input images \emph{with} \acronym{ICC}~profiles the default is to use
    \acronym{CIELUV}~colorspace.

    \genidx{color cube!RGB@\acronym{RGB}}%
    \gensee{RGB@\acronym{RGB} color cube}{color cube, \acronym{RGB}}%
  \item
    Images \emph{without} color profiles and floating-point images are blended in the trivial
    luminance interval (grayscale) or \acronym{RGB}-color cube by default.
  \end{itemize}

  On the order of fast to slow computation, \App{} supports the following blend colorspaces.

  \begin{description}
  \item[\itempar{\code{identity} \\ \code{id} \\ \code{unit}}]\itemend
    Compute blended colors in a na\"ive way sidestepping any dedicated colorspace.
    \begin{itemize}
      \genidx{luminance interval!trivial}%
    \item
      Use trivial, 1-dimensional luminance interval (see
      \equationabbr~\fullref{equ:trivial-luminance-blend}) for grayscale images and

      \genidx{color cube!\acronym{RGB}}%
      \genidx{sRGB@\acronym{sRGB}}%
    \item
      for color images utilize 3-dimensional \acronym{RGB}-cube (see
      \equationabbr~\fullref{equ:trivial-rgb-blend}) spanned by the input \acronym{ICC}~profile
      or \acronym{sRGB} if no profiles are present.  In the latter case, consider passing
      option~\flexipageref{\option{--fallback-profile}}{opt:fallback-profile} to force a
      different profile than \acronym{sRGB} upon all input images.
    \end{itemize}

    \genidx{colorspace!\acronym{CIEL*a*b*}}%
    \gensee{CIEL*a*b*@\acronym{CIEL*a*b*} colorspace}{colorspace, \acronym{CIEL*a*b*}}%
  \item[\itempar{\code{lab} \\ \code{cielab} \\ \code{lstar} \\ \code{l-star}}]\itemend
    Blend pixels in the \acronym{CIEL*a*b*} colorspace.

    \genidx{colorspace!\acronym{CIEL*u*v*}}%
    \gensee{CIEL*u*v*@\acronym{CIEL*u*v*} colorspace}{colorspace, \acronym{CIEL*u*v*}}%
  \item[\itempar{\code{luv} \\ \code{cieluv}}]\itemend
    Blend pixels in the \acronym{CIEL*u*v*} colorspace.

    \genidx{colorspace!\acronym{CIECAM02}}%
    \gensee{CIECAM02@\acronym{CIECAM02} colorspace}{colorspace, \acronym{CIECAM02}}%
  \item[\itempar{\code{ciecam} \\ \code{ciecam02} \\ \code{jch}}]\itemend
    Blend pixels in the \acronym{CIECAM02} colorspace.
  \end{description}

  \ifenblend
  \genidx{optimizer!seam-line}%
    \begin{restrictedmaterial}{\application{Enblend} only.}
      Please keep in mind that by using different blend colorspaces, blending may not only
      change the colors of the output image, but \application{Enblend} may choose different seam
      line routes as some seam-line optimizers are guided by image differences, which are
      different when viewed in different colorspaces.
    \end{restrictedmaterial}
  \fi


  \label{opt:depth}%
  \optidx[\defininglocation]{--depth}%
  \shoptidx{-d}{--depth}%
  \genidx{bits per channel}%
  \gensee{channel!width}{channel, depth}%
  \genidx{channel!depth}%
\item[\itempar{-d \metavar{DEPTH} \\ --depth=\metavar{DEPTH}}]\itemend
  Force the number of bits per channel and the numeric format of the output image, this is, the
  \metavar{DEPTH}.  The number of bits per channel is also known as ``channel width'' or
  ``channel depth''.

  \genidx{requantization}%
  \App{} always uses a smart way to change the channel depth to assure highest image quality at
  the expense of memory, whether requantization is implicit because of the output format or
  explicit through option~\option{--depth}.

  \begin{itemize}
  \item
    If the output-channel depth is larger than the input-channel depth of the input images, the
    input images' channels are widened to the output channel depth immediately after loading,
    that is, as soon as possible.  \App{} then performs all blending operations at the
    output-channel depth, thereby preserving minute color details which can appear in the
    blending areas.

  \item
    If the output-channel depth is smaller than the input-channel depth of the input images, the
    output image's channels are narrowed only right before it is written to the output
    \metavar{FILE}, that is, as late as possible.  Thus the data benefits from the wider input
    channels for the longest time.
  \end{itemize}

  All \metavar{DEPTH} specifications are valid in lowercase as well as uppercase letters.  For
  integer format, use

  \begin{description}
  \item[\code{8}]\itemx[\code{uint8}]\itemend
    Unsigned 8~bit; range: $0\dots255$

  \item[\code{int16}]\itemend
    Signed 16~bit; range: $-32768\dots32767$

  \item[\code{16}]\itemx[\code{uint16}]\itemend
    Unsigned 16~bit; range: $0\dots65535$

  \item[\code{int32}]\itemend
    Signed 32~bit; range: $-2147483648\dots2147483647$

  \item[\code{32}]\itemx[\code{uint32}]\itemend
    Unsigned 32~bit; range: $0\dots4294967295$
  \end{description}

  %% Minimum positive normalized value: 2^(2 - 2^k)
  %% Epsilon: 2^(1 - n)
  %% Maximum finite value: (1 - 2^(-n)) * 2^(2^k)
  For floating-point format, use

  \begin{description}
    \genidx{IEEE754@\acronym{IEEE754}!single precision float}%
    \gensee{single precision float (\acronym{IEEE754})}{\acronym{IEEE754}, single precision float}%
  \item[\code{r32}]\itemx[\code{real32}]\itemx[\code{float}]\itemend
    %% IEEE single: 32 bits, n = 24, k = 32 - n - 1 = 7
    \acronym{IEEE754} single precision floating-point, 32~bit wide, 24~bit significant;

    \begin{compactitemize}
    \item
      Minimum normalized value: \semilog{1.2}{-38}
    \item
      Epsilon: \semilog{1.2}{-7}
    \item
      Maximum finite value: \semilog{3.4}{38}
    \end{compactitemize}

    \genidx{IEEE754@\acronym{IEEE754}!double precision float}%
    \gensee{double precision float (\acronym{IEEE754})}{\acronym{IEEE754}, double precision float}%
  \item[\code{r64}]\itemx[\code{real64}]\itemx[\code{double}]\itemend
    %% IEEE double: 64 bits, n = 53, k = 64 - n - 1 = 10
    \acronym{IEEE754} double precision floating-point, 64~bit wide, 53~bit significant;

    \begin{compactitemize}
    \item
      Minimum normalized value: \semilog{2.2}{-308}
    \item
      Epsilon: \semilog{2.2}{-16}
    \item
      Maximum finite value: \semilog{1.8}{308}
    \end{compactitemize}
  \end{description}

  If the requested \metavar{DEPTH} is not supported by the output file format, \App{} warns and
  chooses the \metavar{DEPTH} that matches best.

  \genidx{OpenEXR@\acronym{OpenEXR}!data format}%
  \begin{restrictedmaterial}{Versions with \acronym{OpenEXR} read\slash write support only.}
    \noindent The \acronym{OpenEXR} data format is treated as \acronym{IEEE754}~float
    internally.  Externally, on disk, \acronym{OpenEXR} data is represented by ``half''
    precision floating-point numbers.

    %% ILM half: 16 bits, n = 10, k = 16 - n - 1 = 5
    \genidx{OpenEXR@\acronym{OpenEXR}!half precision float}%
    \gensee{half precision float (\acronym{OpenEXR})}{\acronym{OpenEXR}, half precision float}%
    \uref{\openexrcomfeatures}{\acronym{OpenEXR}} half precision floating-point, 16~bit wide,
    10~bit significant;

    \begin{compactitemize}
    \item
      Minimum normalized value: \semilog{9.3}{-10}
    \item
      Epsilon: \semilog{2.0}{-3}
    \item
      Maximum finite value: \semilog{4.3}{9}
    \end{compactitemize}
  \end{restrictedmaterial}

  \label{opt:f}%
  \optidx[\defininglocation]{-f}%
  \genidx{size!canvas}%
  \genidx{output image!set size}%
\item[-f \metavar{WIDTH}x\metavar{HEIGHT}%
  \optional{+x\metavar{XOFFSET}+y\metavar{YOFFSET}}]\itemend
  Ensure that the minimum ``canvas'' size of the output image is at least
  \metavar{WIDTH}\classictimes\metavar{HEIGHT}.  Optionally specify the \metavar{XOFFSET} and
  \metavar{YOFFSET} of the canvas, too.

  \prgidx{nona \textrm{(Hugin)}}%
  This option only is useful when the input images are cropped \acronym{TIFF} files, such as
  those produced by \command{nona}.

  Note that option~\option{-f} neither rescales the output image, nor shrinks the canvas size
  below the minimum size occupied by the union of all input images.


  \label{opt:g}%
  \optidx[\defininglocation]{-g}%
  \genidx{alpha channel!associated}%
  \gensee{associated alpha channel}{alpha channel, associated}%
  \gensee{unassociated alpha channel}{alpha channel, associated}%
\item[-g]
  Save alpha channel as ``associated''.  See the
  \uref{\awaresystemsbeextrasamples}{\acronym{TIFF} documentation} for an explanation.

  \appidx{Gimp}%
  \appidx{Cinepaint}%
  \application{The Gimp} before version~2.0 and \application{CinePaint} (see
  \appendixName~\fullref{sec:helpful-programs}) exhibit problems when loading images with
  unassociated alpha channels.  Use option~\option{-g} to work around.  With this flag \App{}
  will create the output image with the ``associated alpha tag'' set, even though the image is
  really unassociated alpha.


  \label{opt:output-mask}%
  \optidx[\defininglocation]{--output-mask}%
  \genidx{mask!output}%
  \gensee{output mask}{mask, output}%
\item[--output-mask\optional{=\metavar{FILE}}]\itemend
  Write the mask of the output to \metavar{FILE}.  The output mask always is a single-channel,
  1~bit deep image, just as the alpha channel to be represented.  If the option
  argument~\metavar{FILE} is omitted, \App{} writes the resulting mask to
  \filename{\val{val:default-output-mask-filename}}.

  The option can become important if the output-file format does not support an alpha channel
  and nevertheless the final mask is desired after \appisdoing.

  The output file itself always remains unaffected of this option.  In particular it gets its
  alpha channel, this is its mask, whenever the output-file format supports one.  To mimic
  option~\option{--output-mask} with such formats, use for example

  \begin{literal}
    convert \val*{val:default-output-filename} -alpha extract \val*{val:default-output-mask-filename}
  \end{literal}

  For \metavar{FILE}s with an unknown extension or without an extension, the type of
  \metavar{FILE} defaults to \code{\val{val:default-fallback-output-mask-file-type}}.

  Examples:

  \begin{literal}
    \# PPM only supports RGB, not RGBA; write \val*{val:default-output-mask-filename} \\
    \app{} --output-mask --output=a.ppm ?.tif \\
    \# Request separate mask as TIFF file \\
    \app{} --output-mask=mask.tif image-??.tif
  \end{literal}

  See also option~\flexipageref{\option{--output}}{opt:output}, which controls the name of the
  output file and \sectionName~\fullref{sec:helpful-libraries} for the \acronym{NetPBM}~library.


  \label{opt:wrap}%
  \optidx[\defininglocation]{--wrap}%
  \shoptidx{-w}{--wrap}%
  \genidx{wrap around}%
\item[\itempar{-w \optional{\metavar{MODE}} \\ --wrap\optional{=\metavar{MODE}}}]\itemend
  Blend around the boundaries of the panorama, or ``wrap around''.

  As this option significantly increases memory usage and computation time only use it, if the
  panorama will be

  \begin{compactitemize}
  \item
    consulted for any kind measurement, this is, all boundaries must match as accurately as
    possible, or

  \item
    printed out and the boundaries glued together, or

    \genidx{virtual reality}%
    \gensee{VR@\acronym{VR}}{virtual reality}%
  \item
    fed into a virtual reality~(\acronym{VR}) generator, which creates a seamless environment.
  \end{compactitemize}

  \noindent Otherwise, always avoid this option!

  With this option \App{} treats the set of input images (panorama) of width~$w$ and height~$h$
  as an infinite data structure, where each pixel~$P(x, y)$ of the input images represents the
  set of pixels~$S_P(x, y)$.

  \begin{geeknote}
    \genidx{Born@\propername{Born, Max}}%
    \genidx{Karman@\propername{von~K\'arm\'an, Theodore}}%
    Solid-state physicists will be reminded of the
    \uref{\wikipediabornvonkarman}{\propername{Born}-\propername{von~K\'arm\'an} boundary
      condition}.
  \end{geeknote}

  \metavar{MODE} takes the following values:

  \begin{codelist}
  \item[\itempar{none \\ open}]\itemend
    This is a ``no-op''; it has the same effect as not giving \sample{--wrap} at all.  The set
    of input images is considered open at its boundaries.

  \item[horizontal]\itemend
    Wrap around horizontally:
    \[
    S_P(x, y) = \{P(x + m w, y): m \in Z\}.
    \]

    \genidx{panorama!360\angulardegree!horizontal}%
    \gensee{360@360\angulardegree{}!horizontal panorama}{panorama, 360\angulardegree}%
    This is useful for 360\angulardegree{} horizontal panoramas as it eliminates the left and
    right borders.

  \item[vertical]\itemend
    Wrap around vertically:
    \[
    S_P(x, y) = \{P(x, y + n h): n \in Z\}.
    \]

    \genidx{panorama!360\angulardegree!vertical}%
    \gensee{360@360\angulardegree{}!vertical panorama}{panorama, 360\angulardegree}%
    This is useful for 360\angulardegree{} vertical panoramas as it eliminates the top and
    bottom borders.

  \item[\itempar{both \\ horizontal+vertical
      \\ vertical+horizontal}]\itemend
    Wrap around both horizontally and vertically:
    \[
    S_P(x, y) = \{P(x + m w, y + n h): m, n \in Z\}.
    \]

    In this mode, both left and right borders, as well as top and bottom borders, are
    eliminated.
  \end{codelist}

  Specifying \sample{--wrap} without \metavar{MODE} selects horizontal
  wrapping.
\end{codelist}

\genidx[\rangeendlocation]{advanced options}


%%% Local Variables:
%%% fill-column: 96
%%% End:
